Skip to content

docs: application architecture concept page#4

Merged
marc0olo merged 3 commits into
mainfrom
docs/concepts-app-architecture
Mar 13, 2026
Merged

docs: application architecture concept page#4
marc0olo merged 3 commits into
mainfrom
docs/concepts-app-architecture

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented Mar 13, 2026 •
edited
Loading

Summary

  • concepts/app-architecture.md page covering how ICP applications are structured
  • Covers the two-canister model, comparison tables (traditional web + Ethereum), architectural patterns, data storage, and frontend options
  • Recommends single-canister as the default starting point for most apps (atomic operations, minimal overhead)
  • Multi-canister (canister-per-service) for when separation of concerns is needed or platform limits are hit
  • Canister-per-subnet for extreme throughput scenarios
  • Removed canister-per-user pattern (misleading about sovereignty without controller ownership)
  • Uses @icp-sdk/core/agent, distinguishes official vs community CDKs
  • Correct terminology: "onchain"/"offchain" (no hyphens), asset canister is not system-provided, compilation happens locally

Sync recommendation

informed by dfinity/portal — application-architectures.mdx, app-architecture.mdx

@marc0olo marc0olo mentioned this pull request Mar 13, 2026
Merged
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented Mar 13, 2026

Review: concepts/app-architecture.md — Changes Requested

Best page of the batch. Ethereum comparison table and architecture decision flowchart are excellent.

1. Wrong crate URL for ic-stable-structures

In the Data storage section:

Rust: ic-stable-structures provides StableBTreeMap

Links to docs.rs/ic-cdk — wrong crate. Should be https://docs.rs/ic-stable-structures/latest/ic_stable_structures/.

2. Broken link: stable-memory.md

Canisters store data in stable memory

docs/guides/backends/stable-memory.md does not exist — no stub was created. Check whether this should map to an existing page (e.g., ../guides/backends/persistence.md or similar), or file a page proposal issue.

✓ Verified

  • All other internal links point to existing stubs
  • multi-canister icskills tag is correct
  • Architecture patterns are sound and well-explained

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented Mar 13, 2026

Review: concepts/app-architecture.md (round 2)

Must fix

  • Wrong crate URL for ic-stable-structures — Links to https://docs.rs/ic-cdk/latest/ic_cdk/ (wrong crate). Should be https://docs.rs/ic-stable-structures/latest/ic_stable_structures/. (Flagged in round 1, still unfixed.)
  • Broken link: ../guides/backends/stable-memory.md — This file does not exist. The closest match is ../guides/backends/data-persistence.md which covers stable structures and upgrade hooks. (Flagged in round 1, still unfixed.)

Suggestions

None beyond the two must-fix items.

Verified

  • All other internal links resolve: canisters.md, network-overview.md, reverse-gas-model.md, chain-fusion.md, https-outcalls.md, ../guides/authentication/internet-identity.md, ../guides/canister-calls/onchain-calls.md, ../guides/frontends/asset-canister.md, ../getting-started/quickstart.md
  • Motoko core library correctly links to https://mops.one/core/docs
  • Factual accuracy confirmed: 500 GiB stable memory, ~1–2s finality, 2 MiB payload limit, Ethereum ~12s block time
  • Architecture patterns and Ethereum comparison table are excellent
  • No dfx references, no .mdx/JSX
  • Frontmatter complete, multi-canister icskill tag correct

marc0olo and others added 2 commits March 13, 2026 12:08
@marc0olo @claude
docs: application architecture concept page
1e61eff 
Explain how ICP applications are structured, covering the default
two-canister model, comparison with traditional web apps and Ethereum,
four architectural patterns (single, per-service, per-subnet, per-user),
data storage, and frontend options.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@marc0olo
fix: address PR #4 review feedback
1d90287
@marc0olo marc0olo force-pushed the docs/concepts-app-architecture branch from b64c5d1 to 1d90287 Compare March 13, 2026 11:10
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented Mar 13, 2026

Feedback addressed:

  • Fixed wrong crate URL: ic-stable-structures now links to docs.rs/ic-stable-structures (was docs.rs/ic-cdk)
  • Fixed broken link ../guides/backends/stable-memory.md → ../guides/backends/data-persistence.md

@marc0olo marc0olo requested a review from Copilot March 13, 2026 14:50
Copilot AI reviewed Mar 13, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds the missing “Application Architecture” concept page describing how ICP apps are structured (canisters + frontend), how requests flow through boundary nodes, and how to choose an architecture as an app scales.

Changes:

  • Replaces the stub concepts/app-architecture.md with an end-to-end architecture overview.
  • Adds comparison tables (traditional web and Ethereum) and a decision guide for selecting multi-canister patterns.
  • Introduces sections on scaling patterns, data storage, and frontend hosting options.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Comment thread docs/concepts/app-architecture.md Outdated
Comment thread docs/concepts/app-architecture.md Outdated
Comment thread docs/concepts/app-architecture.md Outdated
Comment thread docs/concepts/app-architecture.md Outdated
Comment thread docs/concepts/app-architecture.md Outdated
marc0olo
marc0olo commented Mar 13, 2026
View reviewed changes
Comment thread docs/concepts/app-architecture.md Outdated
marc0olo
marc0olo commented Mar 13, 2026
View reviewed changes
Comment thread docs/concepts/app-architecture.md Outdated
marc0olo
marc0olo commented Mar 13, 2026
View reviewed changes
Comment thread docs/concepts/app-architecture.md Outdated
marc0olo
marc0olo commented Mar 13, 2026
View reviewed changes
Comment thread docs/concepts/app-architecture.md Outdated
marc0olo
marc0olo commented Mar 13, 2026
View reviewed changes
Comment thread docs/concepts/app-architecture.md Outdated
marc0olo
marc0olo commented Mar 13, 2026
View reviewed changes
Comment thread docs/concepts/app-architecture.md Outdated
@marc0olo
docs: address review feedback on app architecture page
b9ec588 
- Distinguish official CDKs from community-supported languages
- Fix asset canister not being system-provided
- Replace @dfinity/agent with @icp-sdk/core/agent
- Fix stable memory wording (heap vs stable distinction)
- Fix Motoko persistence wording (not automatic)
- Fix onchain/offchain spelling (no hyphens)
- Remove canister-per-user pattern
- Remove 'default' label from canister-per-service
- Reframe single canister as production-viable
- Fix 'network compiles' to 'compiled locally'
- Soften finality claim with 'typically'
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented Mar 13, 2026

Feedback addressed:

  • Distinguished official CDKs (Motoko, Rust) from community-supported languages
  • Fixed: asset canister is not system-provided, it's a standard canister you deploy
  • Replaced @dfinity/agent with @icp-sdk/core/agent (superseded)
  • Fixed stable memory wording: acknowledged heap vs stable memory distinction
  • Fixed Motoko persistence: removed misleading "automatically" claim
  • Fixed onchain/offchain spelling to no-hyphen convention
  • Removed canister-per-user pattern entirely
  • Removed "default" label from canister-per-service heading
  • Reframed single canister as production-viable (atomic ops, less overhead)
  • Fixed "network compiles" → compiled locally, executed by the network
  • Softened finality claim with "typically"
  • Updated architecture decision table to reflect new framing

@marc0olo marc0olo merged commit 0792526 into main Mar 13, 2026
@marc0olo marc0olo deleted the docs/concepts-app-architecture branch March 13, 2026 17:47
This was referenced Mar 14, 2026
Merged
Closed
@marc0olo marc0olo mentioned this pull request May 9, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@marc0olo